{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. _nb_performance_indicator:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Performance Indicator"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is fundamental for any algorithm to measure the performance. In a multi-objective scenario, we can not calculate the distance to the true global optimum but must consider a set of solutions. Moreover, sometimes the optimum is not even known, and other techniques must be used. \n",
    "\n",
    "First, let us consider a scenario where the Pareto-front is known:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "code": "usage_performance_indicator.py",
    "section": "load_data"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<pymoo.visualization.scatter.Scatter at 0x7fab5a8b6d90>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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2LFjJUm7d+/udM3j6ea/Xwfhpptu0oABA9r7gXfU3Nysyy+/XC+88ELAef+T5ZaWFknSr371K337299uny8lJaW90FpH/nM333xzyOvtK/93ndlfPNzrGTlyZPs/D0n6yU9+EtYdDaEilOMzB0ulrUWS7aUnofVKW5fwxBwAAAB9kp3uUm5GWp/G5GWkxUSRt2DMmTNH48eP17Zt23T33Xervr5edXV1uvXWW/X666+HPO+kSZN03333aceOHSosLNT+/fv10UcfadeuXbriiit03nnnqaioKGDMl7/8ZUnSyy+/rPr6em3atEkul++f4+TJk7Vq1Sq98cYbWrRokerq6tTc3KxHH31U999/v771rW9FNZRfddVVWrRokZ588knddddd+uCDD3Ty5EndddddevLJJ7Vo0SJdeeWV/f6eL3/5yzpx4oR2796tI0eO6IknnlBaWt/+fYwEQjk+s/2e3gO5n/VK2++N7HoAAACQcIoKspQS5C7iFCMtKei8FTxaxo8fH7Dl2V/krLS0tMv7hw0bptdff1033HCDHnroIZ1//vmaNm2arLX60Y9+JEmaNWuWxo8fL0kqLCxsn3/79u0yxrRfO9Mtt9yiF154QceOHdO0adPkdru1YMECXXrppXrllVd0zjnnBNy/ePFiXXfddSosLNQXvvAFjRkzRv/xH//Rfv3WW2/Vc889p7fffltZWVlyu936zW9+o3vvvVfFxcVKSek9Km7cuFHGmPYn+BkZGTLGaPny5ZKkmTNnKiMjQ5K0adMmGWPa+7efae3atXrsscf07LPPavTo0brgggu0detWbdq0SWvXrm2/79ChQzLGaMWKFUH98+zYKm758uW64oordOmll+qSSy7RrFmz9JOf/KTX3zPSTDxVpYtnxpiKnJycnIqKCqeX0rUT+3zvjPfVD/5M8TcAAIAE43+P19/zOdye2nlEy4r39NivPMVIK+dO1jVTu2+lBURDsH8PU6ZMUWVlZaW1dkpf5o+PigmIvIPbQx9HKAcAAEAfzJs6VqNHDtWakmqVddG3PC8jTUsKsuLmXXKgPwjl8DndGN1xAAAASGr5mW7lZ7pVVdcoT029mlpalTp4oPIz3XHzDjkQDoRy+AwK8f/whToOAAAAkK/4GyEcyYxCb/CZMCO64wAAAAAAhHK0GTVRGpfftzHjpvM+OQAAAAD0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\n",
      "text/plain": [
       "<Figure size 576x432 with 1 Axes>"
      ]
     },
     "metadata": {
      "image/png": {
       "height": 372,
       "width": 498
      },
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "import numpy as np\n",
    "from pymoo.factory import get_problem\n",
    "from pymoo.visualization.scatter import Scatter\n",
    "\n",
    "# The pareto front of a scaled zdt1 problem\n",
    "pf = get_problem(\"zdt1\").pareto_front()\n",
    "\n",
    "# The result found by an algorithm\n",
    "A = pf[::10] * 1.1\n",
    "\n",
    "# plot the result\n",
    "Scatter(legend=True).add(pf, label=\"Pareto-front\").add(A, label=\"Result\").show()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. _nb_gd:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Generational Distance (GD)\n",
    "\n",
    "The GD performance indicator <cite data-cite=\"gd\"></cite> measure the distance from solution to the Pareto-front. Let us assume the points found by our algorithm are the objective vector set $A=\\{a_1, a_2, \\ldots, a_{|A|}\\}$ and the reference points set (Pareto-front) is $Z=\\{z_1, z_2, \\ldots, z_{|Z|}\\}$. Then, \n",
    "\n",
    "\\begin{align}\n",
    "\\begin{split}\n",
    "\\text{GD}(A) & = & \\; \\frac{1}{|A|} \\; \\bigg( \\sum_{i=1}^{|A|} d_i^p \\bigg)^{1/p}\\\\[2mm]\n",
    "\\end{split}\n",
    "\\end{align}\n",
    "\n",
    "where $d_i$ represents the Euclidean distance (p=2) from $a_i$ to its nearest reference point in $Z$. Basically, this results in the average distance from any point $A$ to the closest point in the Pareto-front."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "code": "usage_performance_indicator.py",
    "section": "gd"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "GD 0.05497689467314528\n"
     ]
    }
   ],
   "source": [
    "from pymoo.factory import get_performance_indicator\n",
    "\n",
    "gd = get_performance_indicator(\"gd\", pf)\n",
    "print(\"GD\", gd.calc(A))"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. _nb_gd_plus:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Generational Distance Plus (GD+)\n",
    "\n",
    "Ishibushi et. al. proposed in <cite data-cite=\"igd_plus\"></cite> GD+:\n",
    "\n",
    "\\begin{align}\n",
    "\\begin{split}\n",
    "\\text{GD}^+(A) & = & \\; \\frac{1}{|A|} \\; \\bigg( \\sum_{i=1}^{|A|} {d_i^{+}}^2 \\bigg)^{1/2}\\\\[2mm]\n",
    "\\end{split}\n",
    "\\end{align}\n",
    "\n",
    "where for minimization $d_i^{+} = max \\{ a_i - z_i, 0\\}$ represents the modified distance from $a_i$ to its nearest reference point in $Z$ with the corresponding value $z_i$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "code": "usage_performance_indicator.py",
    "section": "gd_plus"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "GD+ 0.05497689467314528\n"
     ]
    }
   ],
   "source": [
    "from pymoo.factory import get_performance_indicator\n",
    "\n",
    "gd_plus = get_performance_indicator(\"gd+\", pf)\n",
    "print(\"GD+\", gd_plus.calc(A))"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. _nb_igd:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Inverted Generational Distance (IGD)\n",
    "\n",
    "The IGD performance indicator <cite data-cite=\"igd\"></cite> inverts the generational distance and measures the distance from any point in $Z$ to the closest point in $A$.\n",
    "\n",
    "\\begin{align}\n",
    "\\begin{split}\n",
    "\\text{IGD}(A) & = & \\; \\frac{1}{|Z|} \\; \\bigg( \\sum_{i=1}^{|Z|} \\hat{d_i}^p \\bigg)^{1/p}\\\\[2mm]\n",
    "\\end{split}\n",
    "\\end{align}\n",
    "\n",
    "where $\\hat{d_i}$ represents the euclidean distance (p=2) from $z_i$ to its nearest reference point in $A$.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "code": "usage_performance_indicator.py",
    "section": "igd"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "IGD 0.06690908300327662\n"
     ]
    }
   ],
   "source": [
    "from pymoo.factory import get_performance_indicator\n",
    "\n",
    "igd = get_performance_indicator(\"igd\", pf)\n",
    "print(\"IGD\", igd.calc(A))"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. _nb_igd_plus:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Inverted Generational Distance Plus (IGD+)\n",
    "\n",
    "In <cite data-cite=\"igd_plus\"></cite> Ishibushi et. al. proposed IGD+ which is weakly Pareto compliant wheres the original IGD is not.\n",
    "\n",
    "\\begin{align}\n",
    "\\begin{split}\n",
    "\\text{IGD}^{+}(A) & = & \\; \\frac{1}{|Z|} \\; \\bigg( \\sum_{i=1}^{|Z|} {d_i^{+}}^2 \\bigg)^{1/2}\\\\[2mm]\n",
    "\\end{split}\n",
    "\\end{align}\n",
    "\n",
    "where for minimization $d_i^{+} = max \\{ a_i - z_i, 0\\}$ represents the modified distance from $z_i$ to the closest solution in $A$ with the corresponding value $a_i$.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "code": "usage_performance_indicator.py",
    "section": "igd_plus"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "IGD+ 0.06466828842775944\n"
     ]
    }
   ],
   "source": [
    "from pymoo.factory import get_performance_indicator\n",
    "\n",
    "igd_plus = get_performance_indicator(\"igd+\", pf)\n",
    "print(\"IGD+\", igd_plus.calc(A))"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. _nb_hv:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Hypervolume"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For all performance indicators showed so far, a target set needs to be known. For Hypervolume only a reference point needs to be provided. First, I would like to mention that we are using the Hypervolume implementation from [DEAP](https://deap.readthedocs.io/en/master/). It calculates the area/volume, which is dominated by the provided set of solutions with respect to a reference point."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div style=\"display: block;margin-left: auto;margin-right: auto;width: 40%;\">\n",
    "![hv](../resources/images/hv.png)\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This image is taken from <cite data-cite=\"hv\"></cite> and illustrates a two objective example where the area which is dominated by a set of points is shown in grey.\n",
    "Whereas for the other metrics, the goal was to minimize the distance to the Pareto-front, here, we desire to maximize the performance metric."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "code": "usage_performance_indicator.py",
    "section": "hv"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hv 0.9631646448182305\n"
     ]
    }
   ],
   "source": [
    "from pymoo.factory import get_performance_indicator\n",
    "\n",
    "hv = get_performance_indicator(\"hv\", ref_point=np.array([1.2, 1.2]))\n",
    "print(\"hv\", hv.calc(A))"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Raw Cell Format",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
